講了大半個月的 Neoj 資料庫管理、查詢、維護與部署，就是都還沒說到開發，無論圖形資料庫多麽強大，最終還是得呈現在商業應用上才有價值。今天開始我們來看看 Neo4j 開發方面的資源～

我打算從前端講到後端，如果你是一位純前端開發者，至少在講完 Neo4j 前端相關的 API 之後，已經有能力自己開發一個完整的應用了。

首先登場的是 Neo4j HTTP API，如果你在使用的是 Neo4j 3.5 或更舊的版本，還有個 Neo4j REST API，但是在 Neo4j 4.0 已經完全移除，官方已不建議使用。

Discovery API

這是一個入口 API，除了查看伺服器的版本，並簡單列出幾個重要 API 的 endpoints
GET http://localhost:7474/

{
    "bolt_routing": "neo4j://localhost:7687",
    "transaction": "http://localhost:7474/db/{databaseName}/tx",
    "bolt_direct": "bolt://localhost:7687",
    "neo4j_version": "4.1.1",
    "neo4j_edition": "enterprise"
}

Neo4j HTTP API 安全性驗證

除了上述的入口 API 之外，其他 API 的呼叫都需要 HTTP 基本認證，簡單的說，你必須把帳密字串 "neo4j:yourpassword" 轉成 BASE64 編碼後放到 Authorization header，例如

Authorization: Basic bmVvNGo6bXlwYXNzd29yZA==

另一個作法則是直接附加在網址上，當然這樣就更不安全了

http://neo4j:yourpassword@localhost:7474/db/neo4j/tx

Trasantion Commit API

疑？怎麼一下子就跳到 Transaction API？這沒錯！Neo4j HTTP API 不管是新增、查詢、修改、刪除全都是共用這組交易 API，即使你沒有要使用交易，仍然是用交易的概念，在一次的 HTTP Request 直接完成交易並 Commit。

POST http://localhost:7474/db/neo4j/tx/commit
Content-Type: application/json

{
  "statements" : [ {
    "statement" : "MATCH (n) WHERE ID(n) = $nodeId RETURN n",
    "parameters" : {
      "nodeId" : 6
    }
  } ]
}

查詢的回傳結果有點冗長，我直接列出大概的結構出來

{
   "results": [
       {
          // first statement's results
           "columns": [],
           "data": [
               {
                   "row": [ row-data ],
                   "meta": [ metadata ]
               },
               {

               }
           ]
       },
       {
            // second statement’s results
       }
   ]
}

Begin Transaction API

接下來我們看看交易的完整流程如圖

(圖片來源：Neo4j 官網)

上圖中最下方那一條流程，就是剛才講過的，直接在一個 HTTP Request 中開啟交易後立即 Commit 結束交易。
其他則都是標準的交易流程，大約步驟如下：

1. POST /db/neo4j/tx 開啟一個新的交易
2. 再來就是根據回應的交易 API endpoint 持續進行交易，這時候會打
   POST /db/neo4j/tx/{transaction_id}
3. 隨時都可以打 Commit API 確認此筆交易，或是 Rollback API 取消
   Commit: POST /db/neo4j/tx/{transaction_id}/commit
   Rollbak: DELETE /db/neo4j/tx/{transaction_id}

每一筆交易的預設 timeout 時間是 60 秒，超過就會自動被 Rollback。

例如，以下就是開啟一個新的交易，並建立兩個新的 Node

POST http://localhost:7474/db/neo4j/tx
Content-Type: application/json
Authorization: Basic bmVvNGo6bXlwYXNzd29yZA==

{
    "statements": [
        {
            "statement": "CREATE (n:Person $props) RETURN n",
            "parameters": {
                "props": {
                    "name": "Egg"
                }
            }
        },
                {
            "statement": "CREATE (n:Tech $props) RETURN n",
            "parameters": {
                "props": {
                    "name": "Neo4j"
                }
            }
        }
    ]
}

Request Body 結構上都是如此，可以在一個 HTTP Request 包含很多個 Cypher，或是分散到多個不同的交易要求，這部分就是各自的應用與需求去做變化了。

{
  "statements": [
    {
      "statement": "...",
      "parameters": {...}
    },
    {
      "statement": "...",
      "parameters": {...}
    },
    ...
  ]
}

延長交易

上面有說 Neo4j 預設的一個交易時間是 60 秒，如果想延長，可以丟一個空的交易內容如下：

{
  "statements" : [ ]
}

Rollback Transaction API

Rollback 只需要打 HTTP DELETE 即可

DELETE http://localhost:7474/db/neo4j/tx/{transaction_id}

查看統計資訊

如果想知道該筆查詢的細節資訊，可以加上 includeStats 如下

{
  "statements" : [ {
    "statement" : "CREATE (n:Person {name: 'Aura'}) RETURN n",
    "includeStats" : true
  } ]
}

以下是一個完整的開始新交易的回傳結果

{
    "results": [
        {
            "columns": [
                "n"
            ],
            "data": [
                {
                    "row": [
                        {
                            "name": "Aura"
                        }
                    ],
                    "meta": [
                        {
                            "id": 9,
                            "type": "node",
                            "deleted": false
                        }
                    ]
                }
            ],
            "stats": {
                "contains_updates": true,
                "nodes_created": 1,
                "nodes_deleted": 0,
                "properties_set": 1,
                "relationships_created": 0,
                "relationship_deleted": 0,
                "labels_added": 1,
                "labels_removed": 0,
                "indexes_added": 0,
                "indexes_removed": 0,
                "constraints_added": 0,
                "constraints_removed": 0,
                "contains_system_updates": false,
                "system_updates": 0
            }
        }
    ],
    "errors": [],
    "commit": "http://localhost:7474/db/neo4j/tx/18/commit",
    "transaction": {
        "expires": "Sat, 10 Oct 2020 16:30:48 GMT"
    }
}

回傳圖形結構資料

除了回傳的節點，若還需要周圍的關係和節點，可以加上 resultDataContents

{
  "statements" : [ {
    "statement" : "CREATE (n:Person {name: 'Aura'}) RETURN n",
    "resultDataContents" : [ "row", "graph" ],
    "includeStats" : true
  } ]
}

這可應用在需要自己設計完全客製的圖形化顯示 Neo4j 資料庫時使用，還記得第一篇說過的用 d3.js 呈現 Neo4j 嗎？就是有用到這個指令。

錯誤處理

需要注意的是，每個 Transaction API 回應的 HTTP Status Code 都是 200，除非 Cypher 語法明顯有誤，判斷是否有錯誤的一個依據是，看是否會有 transaction 這個 key，如果沒有，那表示你語法錯囉！

"transaction": {
    "expires": "Sat, 10 Oct 2020 16:04:24 GMT"
}

以上是今天的分享，學會 Neo4j HTTP API 之後，離自己寫前端應用不遠了～